<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Frequently Asked Questions</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Frequently Asked Questions</h1>



<div id="why-isnt-my-package-being-snapshotted-into-the-lockfile" class="section level2">
<h2>Why isn’t my package being snapshotted into the lockfile?</h2>
<p>By default, <code>renv</code> uses the intersection of:</p>
<ol style="list-style-type: decimal">
<li><p>Packages installed into your project library, and</p></li>
<li><p>Packages which appear to be used in your project, as discovered
by <code>renv::dependencies()</code>,</p></li>
</ol>
<p>in determining which packages should enter the lockfile. The
intention is that only the packages you truly require for your project
should enter the lockfile; development dependencies
(e.g. <code>devtools</code>) normally should not.</p>
<p>If you find a package is not entering the lockfile, you can check the
output of:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">dependencies</span>()</span></code></pre></div>
<p>and see whether usages of your package are reported in the
output.</p>
<p>Note that <code>renv</code>’s dependency discovery machinery relies
on static analysis of your R code, and does not understand all of the
different ways in which a package might be used in a project. For
example, <code>renv</code> will detect the following usages:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="fu">library</span>(dplyr)</span>
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a><span class="fu">library</span>(ggplot2)</span></code></pre></div>
<p>But it will be unable to detect these kinds of usages:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="cf">for</span> (package <span class="cf">in</span> <span class="fu">c</span>(<span class="st">&quot;dplyr&quot;</span>, <span class="st">&quot;ggplot2&quot;</span>)) {</span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a>  <span class="fu">library</span>(package, <span class="at">character.only =</span> <span class="cn">TRUE</span>)</span>
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a>}</span></code></pre></div>
<p>If you use a custom package loader in your project that
<code>renv</code> could feasibly support, please feel free to <a href="https://github.com/rstudio/renv/issues">file a feature
request</a>.</p>
<div id="capturing-all-dependencies" class="section level3">
<h3>Capturing all dependencies</h3>
<p>If you’d instead prefer to capture <em>all</em> packages installed
into your project library (and eschew dependency discovery altogether),
you can do so with:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a>renv<span class="sc">::</span>settings<span class="sc">$</span><span class="fu">snapshot.type</span>(<span class="st">&quot;all&quot;</span>)</span></code></pre></div>
<p>Packages can also be explicitly ignored through a project setting,
e.g. with:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a>renv<span class="sc">::</span>settings<span class="sc">$</span><span class="fu">ignored.packages</span>(<span class="st">&quot;&lt;package&gt;&quot;</span>)</span></code></pre></div>
<p>You might also want to double-check the set of ignored packages
(<code>renv::settings$ignored.packages()</code>) and confirm that you
aren’t unintentionally ignoring a package you actually require.</p>
<p>See the documentation in <code>?snapshot</code> for more details.</p>
</div>
<div id="capturing-explicit-dependencies" class="section level3">
<h3>Capturing explicit dependencies</h3>
<p>If you’d like to explicitly declare which packages your project
depends on, you can do so by telling <code>renv</code> to form
“explicit” snapshots:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" tabindex="-1"></a>renv<span class="sc">::</span>settings<span class="sc">$</span><span class="fu">snapshot.type</span>(<span class="st">&quot;explicit&quot;</span>)</span></code></pre></div>
<p>In this mode, <code>renv</code> will only include packages which are
explicitly listed in the project’s <code>DESCRIPTION</code> file as
dependencies.</p>
</div>
</div>
<div id="how-do-i-update-the-lockfile" class="section level2">
<h2>How do I update the lockfile?</h2>
<p>The most important thing to remember is that
<code>renv::snapshot()</code> captures the state of your project at the
point in time when <code>renv::snapshot()</code> was called. In that
sense, the “right” way to update the lockfile is to:</p>
<ol style="list-style-type: decimal">
<li>Load the <code>renv</code> project,</li>
<li>Make the changes you want; e.g. install packages; call
<code>options(repos = &lt;...&gt;)</code>; …</li>
<li>Call <code>renv::snapshot()</code> to update the lockfile.</li>
</ol>
<p>That said, you are also free to modify the <code>renv.lock</code>
lockfile by hand if necessary; e.g. if you want to manually add / change
repositories, change the version of a package used, and so on. The
<code>renv.lock</code> lockfile is a <a href="https://www.json.org/json-en.html">JSON</a> file, and while no
schema is provided, you should be able to infer the structure from the
existing fields.</p>
<p>The main downside to editing a package record in the lockfile
directly is that you won’t be able to provide a <code>Hash</code> for
that package, and so <code>renv</code> won’t be able to use its global
package cache when installing that package.</p>
</div>
<div id="how-should-i-handle-development-dependencies" class="section level2">
<h2>How should I handle development dependencies?</h2>
<p>This is related to the above question: by design,
<code>renv.lock</code> normally only captures build-time or deploy-time
dependencies; it may not capture the packages that you use in iterative
workflows (e.g. <code>devtools</code>). However, you may want some way
of still ensuring these development dependencies get installed when
trying to restore a project library.</p>
<p>For cases like these, we recommend tracking these packages in a
project DESCRIPTION file; typically, within the <code>Suggests:</code>
field. Then, you can execute:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>()</span></code></pre></div>
<p>to request that <code>renv</code> install the packages as described
in the DESCRIPTION file. In addition, the <code>Remotes:</code> fields
will be parsed and used, to ensure packages are installed from their
declared remote source as appropriate.</p>
</div>
<div id="im-returning-to-an-older-renv-project.-what-do-i-do" class="section level2">
<h2>I’m returning to an older renv project. What do I do?</h2>
<p>Suppose you were using <code>renv</code> to manage an older project’s
dependencies. You have an older lockfile, capturing the dependencies in
use when you were last working with that project. You now need to resume
work on this project – what do you do?</p>
<p>The answer depends on how exactly you want to use the project. Do you
want to treat it as a “time capsule”, with dependencies frozen in time?
Or are the dependencies in this project fluid, and you are primarily
using <code>renv</code> just for isolation of project dependencies?</p>
<p>For time capsules, the solution is to use
<code>renv::restore()</code> to reinstall the exact packages as declared
in the project lockfile <code>renv.lock</code>. You may also need to
find and install the older version of R used previously with that
project, unless your intention is to upgrade R.</p>
<p>For projects with fluid dependencies, one solution is to use
<code>renv::init()</code> to re-initialize the project with a brand new
project library. When <code>renv::init()</code> is invoked, you may see
a question such as:</p>
<pre><code>&gt; renv::init()
This project already has a lockfile. What would you like to do?

1: Restore the project from the lockfile.
2: Discard the lockfile and re-initialize the project.
3: Activate the project without snapshotting or installing any packages.
4: Abort project initialization.</code></pre>
<p>You can select option (2) to instruct <code>renv</code> to
re-initialize the project, effectively discarding the old lockfile and
initializing the project with a new project library. You may also want
to call <code>renv::update()</code> to ensure all packages in the new
project library are updated to the latest-available versions. To update
the version of renv itself that manages the project, call
<code>renv::upgrade()</code>.</p>
<p>If you prefer a more managed approach, you might also consider the
following approach:</p>
<ol style="list-style-type: decimal">
<li><p>Use <code>renv::restore()</code> to restore the project state as
defined in the lockfile,</p></li>
<li><p>Install and update packages deliberately, e.g. via
<code>renv::install()</code>, <code>install.packages()</code>, or other
relevant tools,</p></li>
<li><p>Call <code>renv::snapshot()</code> after you’ve finished updating
the requisite packages, to generate a new lockfile.</p></li>
</ol>
</div>
<div id="why-are-package-downloads-failing" class="section level2">
<h2>Why are package downloads failing?</h2>
<p>Some issues ultimately boil down to a lack of connectivity between
your machine and the R package repositories and remote sources you are
trying to use. If you are working in a corporate environment, it may be
worth confirming whether you have a corporate proxy in place inhibiting
internet access, or whether R and <code>renv</code> need to be
configured in a way compatible with your working environment. This is
often true on Windows machines in enterprise environments, where the
default “wininet” download method may work more reliably than
others.</p>
<p>Note that by default <code>renv</code> attempts to use the
<code>curl</code> command line utility in order to download files and
communicate with remote web services. This is done to enable
authentication with private web services (e.g. private GitHub
repositories).</p>
<p>If you find that downloads work outside of <code>renv</code>
projects, but not within <code>renv</code> projects, you may need to
tell <code>renv</code> to use the same download file method that R has
been configured to use. You can check which download method R is
currently configured to use with:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a><span class="fu">getOption</span>(<span class="st">&quot;download.file.method&quot;</span>)</span></code></pre></div>
<p>And the downloader currently used by <code>renv</code> can be queried
with:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a>renv<span class="sc">:::</span><span class="fu">renv_download_method</span>()</span></code></pre></div>
<p>You can force <code>renv</code> to use the same download method as R
by setting:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" tabindex="-1"></a><span class="fu">Sys.setenv</span>(<span class="at">RENV_DOWNLOAD_METHOD =</span> <span class="fu">getOption</span>(<span class="st">&quot;download.file.method&quot;</span>))</span></code></pre></div>
<p>and, if necessary, you could also set this environment variable
within e.g. your <code>~/.Renviron</code>, so that it is visible to all
R sessions. See <code>?Startup</code> for more details.</p>
<p>In addition, by default, <code>renv</code> places shims on the R
search path that re-routes calls from <code>install.packages()</code> to
<code>renv::install()</code>. If you need to bypass these shims, you can
use <code>utils::install.packages(&lt;...&gt;)</code>; that is, with the
call to <code>install.packages()</code> explicitly qualified with the
package <code>utils::</code>. See <a href="https://rstudio.github.io/renv/articles/renv.html#shims" class="uri">https://rstudio.github.io/renv/articles/renv.html#shims</a>
for more details.</p>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>
